home *** CD-ROM | disk | FTP | other *** search
/ Beginning Mac Programming / Beginning Mac Programming.bin / Open Me for REALbasic 3 / REALbasic 3.2 / Example Projects / Reusable Classes_Code / User Interface / CanvasPaint / Read Me < prev    next >
Text File  |  1999-04-26  |  10KB  |  112 lines
  1. CanvasPaint 1.1
  2. By Dan Vanderkam
  3. dantheox@aol.com
  4.  
  5.    Welcome to CanvasPaint, a wonderfully simple way to add bitmap editing cababilities to your RB programs. CanvasPaint is a REALbasic 2.0 canvas sub-class, so you'll need to have 2.0 (or a reasonably recent DR) to use it. It's extremely simple to set up. Just follow these steps:
  6.  
  7.   1) Drag the CanvasPaint class into your project.
  8.   2) Make a new canvas control, and set its super to CanvasPaint.
  9.  
  10.   And that's all the setup you need! If you run the program now, the user will be able to scribble in thin black lines. However, leaving it like this is a horrible waste, because there are eight more tools that CanvasPaint supports.
  11.  
  12.   The rest of this manual contains info on how to make CanvasPaint do specific things. If the info doesn't make sense to you, open up the example project that came with CanvasPaint. It makes use of all the techniques described here.
  13.  
  14. Changing Tools
  15.   To set a tool, simple use CanvasPaint's tool property. For example, if you wanted to change the tool to the Line tool, you'd use the statement "CanvasPaint.tool=CanvasPaint.toolLine". Now, instead of scribbling, the canvas would allow you to draw lines in the same manner that any other painting program does. There are several other tools. Here are their names, the name of the property that reflects them, and their ID.
  16.  
  17. Selection  : toolSelect   (0)
  18. Pencil     : toolPencil   (1)
  19. Line       : toolLine     (2)
  20. Rectangle  : toolBox      (3)
  21. Oval       : toolOval     (4)
  22. Filled Rect: toolFillBox  (5)
  23. Filled Oval: toolFillOval (6)
  24. Eraser     : toolEraser   (7)
  25. Spray Can  : toolSprayCan (8)
  26. Eye Dropper: toolEyeDrop  (10)
  27. Zoom Lense : toolZoom     (11)
  28.  
  29.    For example, CanvasPaint.tool=toolBox and CanvasPaint.tool=3 would accomplish the exact same things.
  30.  
  31. Changing Colors
  32.    Like most painting programs, CanvasPaint supports multiple colors. To change the foreground color of the current picture, just use the SetColor method. For example, "CanvasPaint.SetColor rgb(s100,100,0)" would change the foreground color to this color, or RGB(100,100,0).  Simple enough.
  33.  
  34.    An important thing to note however, is that simply setting the forecolor of CanvasPaint's graphics object won't work. So just use SetColor. Trust me.
  35.  
  36. Changing Pen Sizes
  37.    You can also change the pen size. To do this, use the SetPenSize method. For example, "CanvasPaint.SetPenSize 15,10" would set the pen to have a width of 15, and a height of 10.
  38.  
  39.    As was the case with changing the color, this can't be done through the graphics object.
  40.  
  41. Scrolling
  42.    One of the most important abilities of CanvasPaint is the ability to scroll. This is done using two methods, and two properties. The simplest method is the ScrollRelative method. "CanvasPaint.ScrollRelative 20, 10" would scroll the picture 20 pixels to the right, and 10 down. Another method is the ScrollAbsolute method, which scrolls to a specific point, rather than in a specific direction.
  43.  
  44.    To find out how much the picture is scrolled at the current moment, use the offsetX and offsetY properties.
  45.  
  46. Accessing the Picture
  47.    If you need to perform some type of operation on the picture that is currently in the CanvasPicture control, simply use the Pic property. To draw a line from code, the command would be "CanvasPaint.Pic.Graphics.DrawLine 0,0,100,100". This is mainly useful for copying, pasting, and saving.
  48.  
  49. Selections
  50.    The current selection is contained in the selectPict property. If there isn't any selection, this property is nil. Essentially, this is useful only for copying selections, though you might find other uses. When the selection changes, the SelChanged event fires. Its isSelection property indicates whether or not a selection exists.
  51.  
  52.    The location of the selection is contained in the selectX, selectY, selectWdt, and selectHgt properties of the CanvasPaint control.
  53.  
  54.    To drop a new selection onto the picture, call the AddSelection method, which takes three parameters: the picture, the x coordinate, and the y coordinate. This is mainly useful for pasting pictures.
  55.  
  56.    To clear the current selection, simply call the ClearSelection method.
  57.  
  58.    To manually set the selected region, call the SetSelRegion method. The paramters that it takes are the x and y coordinate of the top of the selection, as well as the width and height.
  59.  
  60. Zooming
  61.    The major new feature of version 1.1 is the ability to magnify the image to any level. Zooming is incredibly useful, and it's also incredibly simple—just call the SetZoom method.  This method takes one parameter: the new zoom size. For example, CanvasPaint.SetZoom 4.00 would set the zoom level to 400%. The GetZoom method will return the current zoom level. The default zoom level when CanvasPaint starts up is 100%.
  62.  
  63.    Note however, that SetZoom 0.5 will not zoom out. This may be added in a future version, but zooming out is rarely useful, so don't count on it. Also, zooming may give you some problems if the zoom factor isn't an integer. (ie, 150%)
  64.  
  65. Changing Bit Depths
  66.    To change the bit depth of the picture, you use the ChangeBitDepth method. This only takes one parameter—the new bit depth. The current bit depth is contained in the bitDepth property.
  67.  
  68. Changing the Picture Size
  69.    To change the size of the current picture, call the SetPicSize method. It takes three parameters—the new width, the new height, and whether or not to preserve the picture's contents. After calling this, be sure to update any scroll bars for the new info.
  70.  
  71. Spray Can Options
  72.    The Spray Can tool has three options. The first is the flowRate variable. This indicates how many microseconds must pass before more points are laid down by the spray can. The default is 40,000. This is irrelevant when the mouse is moving.
  73.  
  74.   The second property is the sprayDensity property. This indicates how many dots will be added each time the spray can is used. The default is 25.
  75.  
  76.    Finally, the FadeOut property is a boolean. If it's set to true, points placed down by the spray can tool will fade in to the background depending on how far from the mouse they are. This can be used to create some very nice edges for objects which are smooth and jagged at the same time. It's great for fire, too. 
  77.  
  78. The Pencil Tool
  79.   The pencil tool is relatively simple, but it does have one option. In many programs, if you click the pencil tool on a pixel that's the same color as the current drawing color, the pencil acts as an eraser. Most editors for small graphics, or low-bit graphics do this, but not all do (notable exceptions include PhotoShop and Color It!). If you want CanvasPaint to have this behavior, set the PencilErase property to true. Otherwise, set it to false. By default, this property is true. In any case, holding down the shift key makes CanvasPaint use the opposite of the current setting.
  80.  
  81. Disabling
  82.   If, for some reason, you want CanvasPaint to stop controlling a canvas and hand control down to you, set its Disabled property to true. When this property is true, all drawing tools on CanvasPaint are deactivated, and the DisabledPaint, DisabledMouseDown, DisabledMouseDrag, and DisabledMouseUp events in your control begin firing. They function exactly as a normal Canvas'  Paint, MouseDown, MouseDrag, and MouseUp events would. To give control of the canvas back to CanvasPaint, just set the Disabled property to false.
  83.  
  84. Getting the picture out and in
  85.   There are a couple of ways to get a picture OUT of CanvasPaint. For example, if you call the SavePicture method (which takes a folderitem as its parameter), the picture is saved to that file as a PICT. If you call the ExportPicture method (which returns a boolean), the user will save the file with the standard QT Save Image display.
  86.  
  87.    To get a picture IN to CanvasPaint, call the SetPicture method. This takes a picture and an integer (the bit depth of the picture). Use this to load pictures.
  88.  
  89. The Eraser
  90.   The eraser tool is simply the pencil tool, but it always draws white. It's also useful to remember that the eraser uses the same pen width and height settings as all the other tools.
  91.  
  92. Legal Stuff
  93.   This class is written by Dan Vanderkam. Though it is free, it is not open source. If you plan on distributing it, you must include an unaltered copy of this Read Me file, and give me credit for the class. If you write a program that utilizes this class, just give me credit in the About box. If you plan on selling your product, you must contact me so that we can work out some type of agreement.
  94.  
  95. Contact Info
  96.    My email address is dantheox@aol.com, so feel free to send in your comments/suggestions/complaints. 
  97.  
  98. Future Abilities
  99.    These are the features I have planned for future versions:
  100.  
  101. • Antialiasing
  102. • Non-rectangular selections (though this would require that RB had decent graphics support...)
  103. • More options for more tools
  104. • Smoother scrolling, etc.
  105. • Built-in Undoing
  106. • Custom Tools
  107. • Zooming OUT and proper functioning at ALL zoom levels.
  108. • Bug Fixes (of course)
  109.  
  110. Version History
  111. 1.1 - Added Zooming. Added Disabled property, DisabledPaint, DisabledMouseDown, DisabledMouseDrag, and DisabledMouseUp events. Fixed bug with eyedropper on vertically scrolled canvas. Added PencilErase property and corresponding action. Fixed crashing bug with spray can on edge of picture. Added Open event to CanvasPaint instances. Added CanvasPaint URL to Read Me. Holding down shift while drawing an oval/filled oval now makes perfect circles. The eraser tool now works. Added the LocationChanged event. Added Toolbox to example program. Added UI to example. Added SetSelRegion, ClearSelection, SetPicture, SavePicture, ExportPicture methods. Added isSelection argument to SelChanged event.
  112. 1.0 - Initial Release